Amiga News 95

home *** CD-ROM | disk | FTP | other *** search

/ Amiga News 95 / Amiga News 95.iso / dpat / dpat05 / termii / documentation / xcmd.doc < prev next >

Wrap

Text File | 1992-07-21 | 17.8 KB | 443 lines

Le 2 Juillet 1991 Term II version 1.1 (c) 1990,1991 - Eric GONTIER XCMD.doc INTRODUCTION : Term II propose un système de commandes externes, qui permet à d'autres programmes (ou encore des "processus" Amiga) d'envoyer des commandes vers Term II qui en assure l'exécution. L'utilisateur ayant des notions de programmation peut donc s'il le désirer créer de nouveaux programmes qui ajouteront de nouvelles fonctions à Term. Les exemples donnés ici sont prévus pour le langage C (et plus particulièrement le compilateur DICE de Matt Dillon), mais peuvent être adaptés sans trop de difficultés à d'autres langages (Modula 2, Pascal, Aseembleur, etc...). Cette possibilité s'ajoute à celle déjà offerte avec Rexx (voir le fichier SCRIPTS.doc). Le "panel", c'est à dire le tableau de commande est un exemple très simple de processus utilisant cette possibilité. Le source en C est fourni à titre d'exemple. Le texte suivant décrit le mécanisme des XCMD (eXternal CoMmanDs) et s'adresse donc surtout au programmeur désireux de développer ses propres programmes). Si les XCMD sont une extension intéressante de Term II, elle sont aussi un formidable moyen de planter l'Amiga ! Les XCMD permettent à un programmeur d'utiliser Term II comme un ensemble de routines faciles à utiliser, tout en utilisant les possibilités multi-tâches de la machine. LES XCMD : Grâce à l'Amiga, les XCMD ne sont que des messages échangés entre des ports, dans la grande tradition d'Exec. Term offre aux processus externes un port appelé XTERM. C'est avec lui que les échanges de messages se feront. Chaque programme externe doit disposer de son propre port. Dans l'exemple de "panel", le port utilisé à pour nom PANEL. Une réponse doit être faite à tout message reçu. C'est une règle essentiel. Term II s'est réservé deux commandes spéciales (sous forme de messages) : START et STOP. La commande START a deux objectifs : - indiquer au processus externe que l'utilisateur de Term en demande une exécution. - transmettre au processus des informations comme un lock sur le répertoire courant ou un lock sur l'écran utilisé par Term. La commande QUIT est utilisé par Term II pour dire au processus externe de stopper l'exécution et de libérer toutes les ressources acquises. Les commandes qu'un processus peut envoyer vers Term II sont les commandes standards (voir le fichier COMMANDES.doc), plus certaines commandes spécifiques, qui seront décrites dans le paragraphe COMMANDES SPECIALES de ce texte. LA STRUCTURE XCMD : Cette structure définit le format d'une XCMD, c'est à dire le format des messages qui seront échangés entre Term et le processus externe. struct XCMD { struct Message xcmd_Message; long xcmd_TermCmd; struct Screen *xcmd_TermScreen; BPTR xcmd_TermDir; char *xcmd_Command; void *xcmd_Args[16]; BOOL xcmd_TermError; }; Voici la signification de chacun des champs de cette structure: xcmd_Message : Le message standard avec des informations essentielles pour Exec, comme le "reply port" etc... xcmd_TermCmd : 0 si non utilisé. Sinon vaut START ou STOP (voir le fichier XCMD.h) xcmd_TermScreen : Un pointeur sur l'écran utilisé par Term. Il s'agit d'un lock sur un public screen. xcmd_TermDir : lock sur le répertoire de Term II. xcmd_Cmd : Pointeur sur une chaine, contenant la commande que le processus externe veut faire exécuter à Term II. Cette commande est soit une des commandes standards (voir le fichier COMMANDES.doc) soit une commande spéciale (voir le paragraphe COMMANDES SPECIALES de ce document.) xcmd_Args : 16 pointeurs, utiles pour échanger des arguments. C'est au programme appelant (donc au processus externe) de s'assuré que ces pointeurs pointent vers des valeurs effectives. Attention aux gurus ! xcmd_TermError : Quand Term II retourne la XCMD, cette valeur vaut TRUE si une erreur a été détectée. FALSE sinon. LA BOITE A OUTILS DES XCMD : La personne intéressée trouvera plusieurs fichiers à étudier : - XCMD.h : contient la définition de la structure XCMD et la définition des commandes START et STOP. - XCMDTools.h : prototypes des fonctions de la boite à outils (XCMDTools.c) - XCMDTools.c : la boite à outils des XCMD, en sources C - XCMDTools.o : objet compilé avec DICE - Panel.c : un exemple d'utilisation des XCMD, avec l'application "panel". La véritable version est un peu différente pour pouvoir être démarrée depuis le menu principal de Term II. XCMDTool est un ensemble de petites routines dont le but est de faciliter le travail du programmeur : struct XCMD *CreateXCMD(struct MsgPort *); Cette fonction crée une XCMD. La partie Message est correctement initialisée. Le MsgPort donnée en paramètre est celui du processus externe. C'est là que Term enverra sa réponse après avoir exécuté la commande. Les autres champs sont mise à 0. Si tout s'est bien passé, un pointeur sur un XCMD est retournée, sinon NULL. void DeleteXCMD(struct XCMD *); Libère la mémoire utilisée par une XCMD. BOOL SendXCMD(struct XCMD *); Cette fonction envoie l'XCMD donnée en paramètre vers le port XTERM de Term II. Retourne TRUE si l'émission a pu se faire, FALSE sinon. Avant émission, cette routine s'assure de l'existence de XTERM. Un couple Forbid()- Permit() s'assure que XTERM n'est pas détruit pendant l'émission. Term II répondra _toujours_ aux messages reçus. Le programmeur doit tenir compte de ces réponses. Ces routines n'ont bien sûr rien de miraculeux. Elles serviront juste au programmeur débutant. Leur utilisation n'est pas du tout obligatoire. START/STOP : Ces commandes sont envoyées par Term II à la demande de l'utilisateur par une de ces fonctions (voir le fichier COMMANDES.doc) : xcmd_start "nom d'un port" Envoie une commande START vers le port d'un processus externe. Par exemple xcmd_start "PANEL" enverra la commande START au port de nom PANEL. xcmd_stop "nom d'un port" Envoie une commande STOP vers le port d'un processus externe. Le programmeur n'a qu'une seule obligation : il doit répondre à ces commandes car Term II attend une réponse avant de poursuivre son exécution. Il est donc conseillé de répondre le plus rapidement possible. Cependant, lors d'une commande START, Term II s'occupe d'obtenir des locks sur l'écran de Term et sur le répertoire courant de l'application. Le programmeur d'un processus externe devra donc s'assuré qu'il libère bien ces locks, par un UnLock pour le répertoire, et par un UnlockPubScreen pour l'écran. A noter aussi que si Term II avait dans ses préférences des choix impliquant l'ouverture d'un écran, cet écran sera ouvert par Term II pour qu'un lock sur cet écran puisse être transmis au processus externe. De plus, il est très possible que l'utilisateur n'envoie pas ces commandes START ou STOP. Il est possible aussi dans le cas de certaines applications que le processus externe n'ait pas à attendre un ordre START pour commencer à s'exécuter, ou un ordre STOP pour s'arrêter. Le programmeur est libre de ces choix. Ces deux commandes sont les seules que Term II peut envoyer à un processus externe. Pour le reste, c'est toujours le processus externe qui envoie ses commandes vers Term II. Les commandes sont décrites dans le paragraphe suivant, intitulé COMMANDES SPECIALES. COMMANDES SPECIALES : Les commandes transmises par un processus externe à Term II sont des commandes standards (voir le fichier COMMANDES.doc). La commande est envoyée en initialisant correctement une XCMD, et en faisant pointer le champ xcmd_Cmd vers une chaine de caractères contenant la commande. Par exemple : struct XCMD *xcmd = CreateXCMD(MyPort); if(xcmd) { xcmd->xcmd_Cmd = "serial_send \"ceci est un test\""; if(SendXCMD(XCMD)) { /* XCMD bien envoyé. On attend la réponse */ WaitPort(MyPort); GetMsg(MyPort); /* On peut tester xcmd->xcmd_TermError pour */ /* savoir si tout s'est bien passé */ } } Toutefois des fonctions spéciales ont été ajoutées pour que le programmeur puisse tirer partie des possibilités de Term II. Ainsi, les commandes réservées à ARexx, ont un équivalent pour les XCMD. Ces commandes sont réservées à l'usage des XCMD, et peuvent transiter que par le port XTERM. Elles ne sont donc pas reconnues si elles viennent d'un script ARexx. Ces commandes sont décrites ci-après, par ordre alphabétique : xcmd_delay Cette commande est l'équivalent de rexx_delay. Elle permet de faire un délai. xcmd_Args[0] est l'adresse d'un long contenant la valeur du délai en secondes. xcmd_lock_request Cette commande demande à Term II de retourner un lock sur le répertoire de Term II, et un lock sur l'écran de Term II. Si besoin, l'écran sera ouvert par Term II. Cette commande est utile s'il pas prévu qu'une commande START soit transmise au processus extern. Le processus externe devra libérer ces locks lui-même avec les fonctions UnLock et UnlockPubScreen. Les valeurs des locks sont retournés en même temps que la XCMD, dans les champs xcmd_TermScreen et xcmd_TermDir. xcmd_memory_request Cette commande demande à Term II de retoourner les 80 dernier caractères reçus. C'est au processus externe de fournir un pointeur valide vers une chaine de 81 caractères (pour contenir le 0 de fin de chaine) dans laquelle Term II recopiera ces 80 caractères (plus le 0 de fin de chaine). Ce pointeur doit être placé dans le champ xcmd_Args[0] de la XCMD avant d'être envoyé à Term II. xcmd_memory_off Equivalent de rexx_memory_off. Cette commande arrête le mécanisme de memory. Voir le fichier SCRIPTS.doc. xcmd_memory_on Equivalent de rexx_memory_on, cette commande met en route le mécanise de memory. Voir le fichier SCRIPTS.doc. xcmd_setserial Cette commande permet de modifier les paramètres de l'interface série. Elle correspond très exactement à la fonctions xpr_setserial décrite par Willy Langeveld dans la définition du standard XPR 2.0. A l'appel, xcmd_Args[0] doit contenir un long correspondant aux nouveaux paramètres. Term II retourne dans xcmd_Args[15] un long correspondant aux anciens paramètres, ou -1 en cas d'erreur. Si à l'appel xcmd_Args[0] vaut -1, Term II retourne les paramètres courants sans rien changer. Un long définissant les paramètres de l'interface série se compose de la manière suivante : octet 0 : pareil que le champ SerFlags de IOExtSer bit 0 : parité ON si à 1 bit 1 : parité impaire si à 1 bit 2 : 7-wire protocole si à 1 bit 3 : queued break si à 1 bit 4 : rad-boogie si à 1 bit 5 : mode partagé si à 1 bit 6 : mode EOF si à 1 bit 7 : protocole si à 1 octet 1 : bit 0 : parité mark ou space si à 1 bit 1 : parité mark si à 1, space sinon bit 2 : 2 bits de stop si à 1, 1 sinon bit 3 : longueur de mots en lecture de 7 bits si à 1, 8 sinon bit 4 : longueur de mots en écriture de 7 bits si à 1, 8 sinon bit 5 : pas utilisé bit 6 : pas utilisé bit 7 : pas utilisé octet 2 : vitesse, comme définit dans preferences.h - 110 baud = 0 - 300 baud = 1 - 1200 baud = 2 - 2400 baud = 3 - 4800 baud = 4 - 9600 baud = 5 - 19200 baud = 6 - midi = 7 - 38400 baud = 8 - 57600 baud = 9 - 76800 baud = 10 - 115200 baud = 11 octet 3 : non utilisé xcmd_sflush Cette commande vide les buffers de l'interface série. xcmd_squery Cette commande permet d'obtenir le nombre de caractères recus et en attente de lecture dans les buffers de l'interface série. Term II retourne ce nombre dans xcmd_Args[15] ou -1 en cas d'erreur xcmd_sread Cette commande permet de lire des caractères depuis l'interface série. xcmd_Args[0] contient un pointeur sur un buffer, xcmd_Args[1] contient le nombre de caractères à lire, xcmd_Args[2] contient un timeout exprimé en micro-seconds. Au retour, xcmd_Args[15] contient le nombre de caractères lus, ou -1 en cas d'erreur. Si le timeout vaut 0, Term II essaiera de lire autant de caractères que possible : la commande est retournée dès qu'il n'y a plus de caractères à lire, ou dès que xcmd_Args[1] caractères sont lus. ATTENTION : il faut s'assurer d'être bien le seul à lire sur l'interface série. Voir pour celà les commandes serial_on et serial_off dans COMMANDES.doc. xcmd_swrite Cette commande permet d'écrire des caractères sur l'interface série. xcmd_Args[0] contient l'adresse d'un buffer contenant les caractères à écrire, et xcmd_Args[1] contient le nombre de caractères à ecrire. Term II retourne -1 en cas d'erreur dans xcmd_Args[15] xcmd_wait Equivalent de la commande rexx_wait. Voir le fichier SCRIPTS.doc. xcmd_Args[0] pointe sur un long contenant la valeur du premier délai en secondes. xmd_Args[1] pointe sur un long contenant la valeur du second délai, en secondes.